import "code.google.com/p/go.net/websocket"
websocket包实现了WebSocket协议的客户端和服务端，参见RFC 6455。
const (
ProtocolVersionHybi13 = 13
ProtocolVersionHybi = ProtocolVersionHybi13
SupportedProtocolVersion = "13"
ContinuationFrame = 0
TextFrame = 1
BinaryFrame = 2
CloseFrame = 8
PingFrame = 9
PongFrame = 10
UnknownFrame = 255
)
var (
ErrBadMaskingKey = &ProtocolError{"bad masking key"}
ErrBadPongMessage = &ProtocolError{"bad pong message"}
ErrBadClosingStatus = &ProtocolError{"bad closing status"}
ErrUnsupportedExtensions = &ProtocolError{"unsupported extensions"}
ErrNotImplemented = &ProtocolError{"not implemented"}
)
var (
ErrBadProtocolVersion = &ProtocolError{"bad protocol version"}
ErrBadScheme = &ProtocolError{"bad scheme"}
ErrBadStatus = &ProtocolError{"bad status"}
ErrBadUpgrade = &ProtocolError{"missing or bad upgrade"}
ErrBadWebSocketOrigin = &ProtocolError{"missing or bad WebSocket-Origin"}
ErrBadWebSocketLocation = &ProtocolError{"missing or bad WebSocket-Location"}
ErrBadWebSocketProtocol = &ProtocolError{"missing or bad WebSocket-Protocol"}
ErrBadWebSocketVersion = &ProtocolError{"missing or bad WebSocket Version"}
ErrChallengeResponse = &ProtocolError{"mismatch challenge/response"}
ErrBadFrame = &ProtocolError{"bad frame"}
ErrBadFrameBoundary = &ProtocolError{"not on frame boundary"}
ErrNotWebSocket = &ProtocolError{"not websocket protocol"}
ErrBadRequestMethod = &ProtocolError{"bad method"}
ErrNotSupported = &ProtocolError{"not supported"}
)
var JSON = Codec{jsonMarshal, jsonUnmarshal}
JSON是从WebSocket连接中发送/接受json数据的编解码器。
简单用法举例：
import "websocket"
type T struct {
Msg string
Count int
}
// receive JSON type T
var data T
websocket.JSON.Receive(ws, &data)
// send JSON type T
websocket.JSON.Send(ws, data)
var Message = Codec{marshal, unmarshal}
Message是从WebSocket连接中发送/接受文本和二进制数据的编解码器。要发送/接收文本数据，应使用string类型；要发送/接收二进制数据，应使用[]byte类型。
简单用法举例：
import "websocket"
// receive text frame
var message string
websocket.Message.Receive(ws, &message)
// send text frame
message = "hello"
websocket.Message.Send(ws, message)
// receive binary frame
var data []byte
websocket.Message.Receive(ws, &data)
// send binary frame
data = []byte{0, 1, 2}
websocket.Message.Send(ws, data)
type ProtocolError struct {
ErrorString string
}
ProtocolError代表WebSocket协议错误。
func (err *ProtocolError) Error() string
type DialError struct {
*Config
Err error
}
DialError代表与WebSocket服务端建立连接时出现的错误。
func (e *DialError) Error() string
func Origin(config *Config, req *http.Request) (*url.URL, error)
Origin解析req的头域的Origin头，如果没有该头，会返回(nil, nil)。
type Config struct {
// WebSocket服务端的地址
Location *url.URL
// Websocket客户端的起点
Origin *url.URL
// WebSocket的子协议
Protocol []string
// WebSocket协议的版本
Version int
// 安全WebSocket（wss）的TLS配置
TlsConfig *tls.Config
// 启用WebSocket的握手应额外发送的头域
Header http.Header
// 内含隐藏或非导出字段
}
Config代表一个WebSocket配置。
func NewConfig(server, origin string) (config *Config, err error)
NewConfig创建一个用于客户端连接的新WebSocket配置。
type Addr struct {
*url.URL
}
Addr实现了net.Addr接口，用于WebSocket。
func (addr *Addr) Network() string
Network返回WebSocket的网络类型："websocket"。
type Conn struct {
PayloadType byte
// 内含隐藏或非导出字段
}
Conn代表一个WebSocket连接。
func Dial(url_, protocol, origin string) (ws *Conn, err error)
Dial打开一个新的WebSocket的客户端连接。
origin := "http://localhost/"
url := "ws://localhost:12345/ws"
ws, err := websocket.Dial(url, "", origin)
if err != nil {
log.Fatal(err)
}
if _, err := ws.Write([]byte("hello, world!\n")); err != nil {
log.Fatal(err)
}
var msg = make([]byte, 512)
var n int
if n, err = ws.Read(msg); err != nil {
log.Fatal(err)
}
fmt.Printf("Received: %s.\n", msg[:n])
func DialConfig(config *Config) (ws *Conn, err error)
DialConfig使用配置config打开一个新的WebSocket的客户端连接。
func NewClient(config *Config, rwc io.ReadWriteCloser) (ws *Conn, err error)
NewClient使用配置config通过包装rwc接口创建一个新的WebSocket的客户端连接。
func (ws *Conn) IsClientConn() bool
func (ws *Conn) IsServerConn() bool
func (ws *Conn) LocalAddr() net.Addr
LocalAddr在客户端会返回配置的Origin字段值，在服务端会返回配置的Location字段值。
func (ws *Conn) RemoteAddr() net.Addr
RemoteAddr在客户端会返回配置的Location字段值，在服务端会返回配置的Origin字段值。
func (ws *Conn) Config() *Config
Config返回WebSocket的配置。
func (ws *Conn) Request() *http.Request
Request返回升级到WebSocket协议的请求；在客户端，会返回nil。
func (ws *Conn) SetDeadline(t time.Time) error
SetDeadline设置该连接的网络读写期限。
func (ws *Conn) SetReadDeadline(t time.Time) error
SetReadDeadline设置该连接的网络读期限。
func (ws *Conn) SetWriteDeadline(t time.Time) error
SetWriteDeadline设置该连接的网络写期限。
func (ws *Conn) Read(msg []byte) (n int, err error)
Read实现了io.Reader接口：它从WebSocket连接读取框架数据。如果msg不能放入全部框架数据，它会 写满msg，下一次调用Read会写入剩下的框架数据。本方法可以读取文本框架数据和二进制框架数据。
func (ws *Conn) Write(msg []byte) (n int, err error)
Write实现了io.Writer接口：它将数据编码为框架数据写入WebSocket连接。
func (ws *Conn) Close() error
Close实现了io.Closer接口。
type Codec struct {
Marshal func(v interface{}) (data []byte, payloadType byte, err error)
Unmarshal func(data []byte, payloadType byte, v interface{}) (err error)
}
Codec代表一个编解码器，它有两个对称的用于编解码的函数类型字段。
func (cd Codec) Receive(ws *Conn, v interface{}) (err error)
Receive从ws获取单个框架，使用cd.Unmarshal反序列化数据并填充进v。
func (cd Codec) Send(ws *Conn, v interface{}) (err error)
Send使用cd.Marshal将v序列化后编码为单个框架写入ws。
type Server struct {
// Config是建立新WebSocket连接的WebSocket配置。
Config
// Handshake是可选的握手（检验）函数。
// 例如，你可以检查或者不检查请求的Origin头。
// 另一个例子，你可以选择config的协议。
Handshake func(*Config, *http.Request) error
// Handler处理单个WebSocket连接。
Handler
}
Server代表一个WebSocket的服务端。
func (s Server) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP实现了用于WebSocket连接的http.Handler接口。
type Handler func(*Conn)
Handler是一个简单的服务浏览器WebSocket客户端的接口。它默认会检查请求的Origin头是否是合法的URL。如果你使用Server代替Handler，你可以在Handshake函数类型字段里检查请求的Origin头。因此，如果你想要接受非浏览器的客户端（不发送Origin头），你可以使用Server，它在握手时不会检查Origin。
package websocket_test
import (
"io"
"net/http"
"code.google.com/p/go.net/websocket"
)
// Echo the data received on the WebSocket.
func EchoServer(ws *websocket.Conn) {
io.Copy(ws, ws)
}
// This example demonstrates a trivial echo server.
func ExampleHandler() {
http.Handle("/echo", websocket.Handler(EchoServer))
err := http.ListenAndServe(":12345", nil)
if err != nil {
panic("ListenAndServe: " + err.Error())
}
}
func (h Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP实现了用于WebSocket连接的http.Handler接口。